Skip to content

feat(server): Claude threads apply their MCP profile's outside servers - #528

Open
scuttletoby wants to merge 6 commits into
mainfrom
fork/mcp-profile-claude-servers
Open

scuttletoby wants to merge 6 commits into
mainfrom
fork/mcp-profile-claude-servers

Conversation

@scuttletoby

@scuttletoby scuttletoby commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

Why

PR 2 of the MCP profile design (#145): "Claude: outside servers". PR 1 (#227) added the settings and the pure resolver, but nothing called the resolver. With this PR a Claude thread's profile reaches its session. Per #101, a profile that cannot be applied refuses the turn and says why and how to fix it. It never starts the turn with every tool.

Depends on #533 (step 1 for the fix round's one new seam line; #527 merged and announced the first 12). A PR is judged by main's seam list, so this PR's seam check fails until #533 merges. After that, main needs merging in once more; the list conflict resolves to this PR's side.

Fix round (both reviews)

Finding Before After
B1 Servers that load anyway (an IT-managed policy drops T3's allowlist, an agent file's mcpServers, a server added mid-session) Checked only once, at open. A call to such a server went through. A PreToolUse hook refuses, at the moment of the call, any mcp__<server>__… tool, and ListMcpResourcesTool/ReadMcpResourceTool naming a server outside the profile. It uses Claude's mcp_server.name when given, else the tool-name prefix, normalised as the CLI does (claude.ai Drive → claude_ai_Drive). Claude gets the reason as the call's result, and the turn goes on. Hooks run in every permission mode and inside sub-agents. With all there is no hook.
B2 A failed settings read with no profile set Refused every Claude turn: getSettings also reads provider secrets, so an unrelated secret-store error blocked Claude. Falls back to all with a log warning, as upstream's own reads in the adapter do. It refuses (#101) only when the settings this adapter last read had something set that can narrow a profile.
A2 Reuse key Plan found by object identity. A reordered or rebuilt key line silently keyed t3-only like all, so a narrowed thread could reuse its wider process. Upstream's key line takes only mcpOverrides, and a PR may not change an upstream line (the seam check refuses lost lines), so the key cannot take the plan as an argument. Overrides with no worked-out plan now get a key no other turn has: a reorder opens a new process each turn and never reuses a wider one. A two-turn test locks both directions; with the lines reordered on purpose, it fails.
A1/B3 Remote-delegated child The comment said a parent "on another machine" refuses; it does not. Behaviour kept (decided): such a child gets this machine's profile for its role. The comment and docs now say so. #532 tracks carrying the parent's profile.
Nits No timeout on the start-time check. The leak refusal named only a managed policy. A missing settings service was silent. The check times out after 5 minutes (as Claude's own boot is bounded), then closes the session and refuses. The refusal names --mcp-config in the Claude launch arguments too. A missing settings service logs a warning once.

Guaranteed for a profile other than all: no MCP tool call or resource read reaches a server the profile leaves out, whatever loaded it. A session that shows such a server at start, or does not list its servers within 5 minutes, never starts the turn. With no profile set, sessions open exactly as before: no hook, no status call, the same key, and no refusal from a failed settings read.

Not guaranteed:

  • A server outside the profile may still load (and spend its startup) when a managed policy or --mcp-config adds it; its calls are refused.
  • A profile set in the very settings change whose read then fails is not seen until a read succeeds. Turns then follow the settings read last (all if nothing was set), with a warning.
  • A settings.json that does not parse loads as defaults (upstream's rule), so its profiles do not apply until it is fixed; upstream logs that.
  • An older Claude that sends no mcp_server is matched by tool-name prefix, so a server named like docs__x passes under a profile that names docs.
  • A remote-delegated child gets this machine's profile (MCP profiles: carry the parent's profile with a cross-machine delegation #532).
  • A profile change applies from the next turn; a message steered into a running turn keeps its session.

What changes

  • apps/server/src/fork/claudeMcpProfile.ts (new, fork-owned) turns the resolver's result into a Claude plan:
    • all: no new options. The session opens exactly as before.
    • t3-only or servers: []: strictMcpConfig: true.
    • A named list: managedSettings.allowedMcpServers with the named servers plus T3's own (t3-code).
    • Refused (typed ClaudeMcpProfileError, message shown in the thread) in these cases:
      • the profile is missing or broken, or the lineage is bad (the resolver's own messages);
      • a parent thread cannot be read and the thread has no pick of its own;
      • the profile's t3Tools is not "all", because nothing applies T3 tool groups until the T3 tool filter PR;
      • settings cannot be read while the settings last read had a profile set (with none set, the thread gets all and a warning).
    • At each tool call (fix round): a PreToolUse hook refuses a call to a server outside the plan.
    • After the session starts, T3 asks Claude for its MCP servers (mcpServerStatus). If any server is there that the plan leaves out (any status but disabled), T3 closes the session and refuses the turn. This catches the cases T3's options cannot control:
      • an IT-managed Claude policy, which drops T3's managedSettings;
      • a --mcp-config in the user's Claude launch arguments, which strict mode keeps;
      • an older CLI.
  • Lineage: parents are read from the projection store only when some setting needs them (thread picks, a project value, or a sub-agent rule other than inherit). With no profile set, no thread is read.
  • Live query: the plan is part of the live-query key, so a profile change opens a new Claude process. Background work still blocks that, as for any setting change. For all the key is byte-for-byte what it was.
  • Upstream files: additions only (13 lines: 12 announced in fork seams: announce the seam lines of MCP profiles part 2 (step 1) #527, 1 in fork seams: announce the MCP profile hooks line of PR 528 (step 1) #533), no upstream line changed:
    • ClaudeAdapterV2.ts (11: the 13th merges the profile's hook into the adapter's hooks);
    • ProviderTurnStartService.ts (1): the refusal counts as "refused before the prompt";
    • failure.ts (1): the refusal's message is shown, not hidden as a generic error.
  • Docs: docs/fork/README.md (server.mcpProfiles) and the FORK_CHANGES.md row.

The 30-minute check

Read in SDK 0.3.321 (sdk.d.ts), in the Claude Code 2.1.326 binary's code, and tried live. The live probe opened a session with no prompt sent (no API turn) and persistSession: false, then read mcpServerStatus().

1. Does strictMcpConfig also drop plugin servers and account connectors? Yes, both.

  • claude.ai connectors: dropped. Observed live: the account's connector (claude.ai Claude Docs, 8 tools) is listed without strict and absent with strict. The CLI's own text for this case reads: "claude.ai connectors are not loaded in this Claude Code session (MCP servers are restricted to explicitly passed config here, e.g. --strict-mcp-config or --bare)".
  • Plugin servers: dropped. The SDK documents it: "ignoring all other MCP configurations: project .mcp.json, user settings, plugins, and on-disk agent frontmatter". The CLI's plugin-server lookup returns an empty set under strict. I could not show this live: my throwaway local plugin's server did not load even without strict.
  • Project .mcp.json: dropped (observed live).
  • What strict keeps: servers passed by the host (T3's own t3-code, which setMcpServers adds after start; observed still registered under strict), --mcp-config servers, and servers declared inline in SDK-passed agents definitions. T3 passes no agents. The --mcp-config case is why the post-start check exists.
  • The allowlist (named lists): observed live, allowedMcpServers: [t3probe, projsrv] kept exactly those two and dropped the claude.ai connector. Per the SDK, an IT-managed settings tier on the machine drops these parent-supplied managedSettings; the post-start check turns that into a refusal.

2. Is the visibility rule asked on tools/call or only on tools/list? Both.

  • In Effect's McpServer.visibility (.repos/effect/packages/effect/src/ai/McpServer.ts), the check runs "on list requests and on calls, reads, gets and completions". When it returns false, the tool is left out of lists, and a call fails as if the tool were not registered (notFound).
  • T3's only visibility today, layerDeferredListing in McpHttpServer.ts, returns true for every method but tools/list on purpose ("Calls are never gated"). So the T3 tool filter (a later PR) gates calls for free, as long as its check does not short-circuit on method.

Tool counts before and after (on one real machine)

The machine has one claude.ai connector (8 tools) and, for the probe, one project .mcp.json server. "Outside" means every MCP server except T3's own:

Profile Outside servers in the session Outside tools
none / all (before and after) project server, claude.ai Claude Docs 8
t3-only (strict) none 0
{ servers: ["projsrv"] } (allowlist) project server only 0 of the connector's 8

T3's own tools are unchanged by this PR; the t3Tools filter comes later.

Default behaviour is unchanged

claudeMcpProfile.adapter.test.ts checks the default case: with server settings that set no profile, the Claude session opens with neither strictMcpConfig nor managedSettings, and T3 never asks Claude for its servers (that stub dies if called). The other ~460 Claude adapter tests run without settings and pass unchanged. In claudeMcpProfile.test.ts, "with no profile set, a child gets all and no parent is read" uses a store that dies on read.

Tests: fail before, pass after

  • With the 12 upstream lines reverted (fork module kept), claudeMcpProfile.adapter.test.ts fails 4 of 5: t3-only strict, the allowlist, refusal of a missing profile, and refusal plus close on a leaked server. The default test passes both before and after, as it should.
  • Fix round: against the PR's previous claudeMcpProfile.ts (stub exports added only so the new tests import), 7 tests fail: the call-time refusal (adapter), the leaked-server and resource rows of the guard table, the fail-closed key, the no-profile fallback on a failed read, and the status timeout. All pass now (76 in the three MCP profile files). The two-turn reuse test passes on both; it is the lock for the key, and fails when the key line is moved above the profile line.
  • After: 13 new tests pass, plus all fork tests. ClaudeAdapterV2.test.ts: 466 of 467. The one failure, "forks a session from its original directory…", is environmental: this machine's node lacks libatomic.so.1. It fails the same way on main.
  • Typecheck, lint, fmt and knip are clean (vp run check:changed).

Review: the state question

  • Runs again: each turn rebuilds the plan. Same profile, same key, so the live process is reused. A changed profile opens a new process, unless background work is running; then upstream's "wait or stop" refusal applies.
  • Stops half-way:
    • A refusal from the plan happens before the live process is touched; the old process keeps running.
    • A refusal from the post-start check closes the new process inside the open's own onError path, the same cleanup as a failed open.
    • The turn counts as refused before the prompt, so the message was never sent to Claude.
  • Old or empty state:
    • Settings without the keys decode to all, so behaviour is unchanged.
    • A hand-edited broken value is refused, never widened (the resolver's rule).
    • A child whose parent was deleted is refused only when a setting needs the lineage and the child has no pick of its own.
    • A continuation turn (draining a live process) is refused too while the profile cannot apply.

Decisions for reviewers

  1. t3Tools other than "all" refuses on Claude until the T3 tool filter lands. Following Owner question: when a thread's tool profile cannot be applied, refuse to start or start with all tools? #101 literally: starting with all T3 tools would quietly widen. Until then such profiles are usable on no Claude thread.
  2. A task delegated from another machine has no local parent (parentThreadId: null). It gets this machine's role default (mcpSubagentProfile, else mcpProfile), not its remote parent's profile. Kept in the fix round; the docs say so, and MCP profiles: carry the parent's profile with a cross-machine delegation #532 tracks carrying the parent's profile.
  3. Other providers do not apply profiles yet. They still start with everything, as before this PR (the docs say so). They need their own PRs, or a refusal for "not supported", per Owner question: when a thread's tool profile cannot be applied, refuse to start or start with all tools? #101.
  4. The post-start check runs once, at session start. A server that appears later in the same session (a plugin installed mid-session, a connector fetched late) is not refused at start, but its calls are refused by the call-time guard (fix round).
  5. Size: 555 changed lines, over the medium target of 400. The parts: the fork module (~200), tests (~260, at the adapter layer because the wiring is the risky part), and the seam list (23).

Upstream fit

Fork-only feature, kept out of upstream's files except 12 added lines. Upstream has no MCP profile concept. If upstream adds per-thread MCP selection, claudeMcpProfilePlan maps onto it, and the seam lines go. The SDK features used (strictMcpConfig, managedSettings.allowedMcpServers, mcpServerStatus) are public SDK options.

General vs project

General: any T3 user with MCP servers in their Claude config can limit what a thread sees, and nothing changes for anyone who sets no profile. Nothing here is specific to one project or machine; the names in the docs (claude.ai Calendar) are examples.

Claude Opus 5.5 in Claude Code (T3 Code harness).

🤖 Generated with Claude Code

noreply and others added 3 commits November 19, 2026 12:30
MCP profiles part 2. A Claude thread's profile now reaches its session:
t3-only and an empty server list open Claude in strict MCP mode, and a
named list passes an allowlist of those servers (plus T3's own). A profile
that cannot be applied refuses the turn with a message that says why and
how to fix it, and a started session that still shows a server the
profile leaves out is closed and refused. With no profile set, nothing
changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Keep main's prepare-server-compile-cache.cjs seam entry and add this PR's three entries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

Review (independent, Opus)

Reviewed head c1426e6f: the PR text, the diff, the resolver (apps/server/src/fork/mcpProfile.ts), openQuery in ClaudeAdapterV2.ts, the query runner's open/setMcpServers path, the refusal plumbing (ProviderTurnStartService.ts, failure.ts) and the production layer wiring.

Verdict: no blocking findings. I found no path where a thread opens a Claude process with more outside servers than its profile allows (the remote-parent case below is a documented rule, not a leak). No path swallows a refusal.

Checked and fine

  • Tests fail on old code: with the 3 upstream files reverted to main (fork module kept), claudeMcpProfile.adapter.test.ts fails 4 of 5; the default case passes both ways. On the PR, the 3 MCP profile test files pass (63/63).
  • Live-process key (runs again): in a scratch probe, claudeEffectiveQueryPolicyKey differs between none, t3-only and a named list, so a narrowed profile opens a new process. A custom profile with servers: "all" gives a key identical to no profile.
  • No profile set: decodes to all; needsLineage is false, so no parent read; no mcpServerStatus call; options and key are unchanged. Skipping the lineage is equivalent there, because every thread in it resolves to the same mcpProfile.
  • Refusals: a missing or broken profile, a bad lineage, a parent that cannot be read (also when a store read errors), unreadable settings, t3Tools not "all", an error from mcpServerStatus, and any non-disabled server outside the plan all refuse. Each is tagged ClaudeMcpProfileError, counted as refused-before-prompt, and its message is curated. resumeTurn and continuation turns go through the same openQuery, so they refuse too.
  • Stops half-way: a plan refusal happens before existing.query.close. A post-start refusal closes the new session; the runner's MCP-timeout retry reopens with the same profile options. openedNativeThreads is not marked on refusal, which matches upstream's failed-open handling.
  • Production wiring: the provider registry is built inside ProviderInstanceRegistryHydration.layer, which requires ServerSettingsService and gets SqlClient from SqlitePersistence.layerConfig. So the serviceOption fallbacks do not trigger in the real server.
  • Named but unconfigured server: goes on the allowlist, loads nothing, no refusal. That matches the resolver's "keeps nothing" rule.

Findings (most severe first)

  1. SHOULD-FIX: the comment says a remote parent refuses; the code lets the child resolve on its own. apps/server/src/fork/claudeMcpProfile.ts:152 says "A parent that is gone (or on another machine) cannot cut the profile down". But a task delegated from another machine has parentThreadId: null, so the loop never sets parentMissing and nothing refuses.
    Scenario: on machine 1 the owner picks t3-only for thread A. A delegates to machine 2, where mcpSubagentProfile is inherit and mcpProfile is all. The child on machine 2 gets every outside server, though "inherit" reads as "A's profile".
    PR decision 2 states this on purpose, so it is not a leak by the written rule. Either fix the comment (say remote parents are not read, and the child gets this machine's role default) and put the same sentence in docs/fork/README.md, or carry the parent's resolved profile in the delegation request in a later PR. Owner call; I lean towards fixing the comment and docs now and opening an issue for the carry.

  2. SHOULD-FIX: the plan reaches the live-process key through a WeakMap keyed by object identity, and no test covers it. claudeMcpProfile.ts:162-168,201 / ClaudeAdapterV2.ts:3562,12785-12787. It is correct today (the probe above). But it only works because mcpProfiles(appThread, mcpOverrides) runs before claudeEffectiveQueryPolicyKey(queryPolicy, mcpOverrides) on the same object.
    Scenario: a later upstream merge reorders those two lines, or rebuilds or spreads mcpOverrides between them. planKeyFor then returns undefined, so t3-only keys like all. A thread narrowed between turns then reuses its wider live process, and no test fails.
    Fix: pass the plan key explicitly, e.g. claudeEffectiveQueryPolicyKey(queryPolicy, mcpOverrides, mcpProfile). That is still one added line plus one parameter. Also add an adapter test: turn 1 under all, settings changed to t3-only, turn 2 opens a second process with strictMcpConfig.

  3. NIT: a steer goes to the process the turn started with. ClaudeAdapterV2.ts:~13883 (existing.query.offer).
    Scenario: a turn runs under all; the owner switches the thread to t3-only and sends a steer. Claude acts on the new message with the outside servers still loaded. This is arguably right (a steer belongs to the running turn), but the docs could say "a profile change applies from the next turn".

  4. NIT: the post-start check runs once, right after open. claudeMcpProfile.ts:207-228. A server that registers after the first mcpServerStatus (a claude.ai connector fetched late, or a plugin installed mid-session) is not caught. This matters only when strict mode or the allowlist is not honoured (a managed policy, an old CLI, --mcp-config). PR decision 4 covers the plugin case; the late connector is the same gap.

  5. NIT: the leaked-server refusal names only a managed policy. claudeMcpProfile.ts:226. The PR text names --mcp-config in the Claude launch arguments as the other known cause (strict mode keeps it), so the fix text should mention it too.

  6. NIT: with no settings service the profile falls back to all silently. claudeMcpProfile.ts:189. This cannot happen in the real server (see wiring above). A one-time logWarning would make a future wiring change visible instead of quietly widening.

State question summary

  • Runs again: the plan is rebuilt every turn and the key follows it.
  • Profile deleted or renamed: refuses before touching the live process; the old process stays idle until it is replaced.
  • Settings changed while background work runs: upstream's "background work blocks replacement" refusal applies.
  • Stops half-way: the new process is closed and the prompt was never sent.
  • Old or empty settings: behave exactly as before.
  • Unknown name or broken entry: refused.
  • Empty list: strict mode.
  • Parent gone or store error: refused unless the thread has its own pick.

@scuttletoby

Copy link
Copy Markdown
Owner Author

Review (independent, Opus)

Reviewed head c1426e6f45 on a fresh clone. I read the PR text, the diff, the resolver (fork/mcpProfile.ts), makeClaudeQueryOptions, openQuery, the runner's open/retry, ProviderTurnStartService.refusedBeforePrompt, the registry/hydration layer wiring, and the SDK 0.3.321 sdk.d.ts text for strictMcpConfig, managedSettings and allowedMcpServers.

Verdict: no blocking findings. The main path is sound:

  • Every Claude turn, including resumeTurn, goes through openQuery, and that is the only queryRunner.open call site.
  • The plan is worked out before existing is touched, so a refused plan leaves the live process alone.
  • The runner's registration-timeout retry keeps the profile options.
  • A refusal reaches the thread through PROMPT_REFUSAL_TAGS and failure.ts; it is not swallowed.
  • In production the adapter's context has both ServerSettingsService and SqlClient: hydration requires the settings service, and it provides SqlitePersistence itself.

Two findings are worth fixing first (1 and 2 below).

1. SHOULD-FIX: servers that start after the one-time check are never checked, which matters exactly when T3's allowlist is dropped

apps/server/src/fork/claudeMcpProfile.ts:207-226 and ClaudeAdapterV2.ts:12974

Per sdk.d.ts, managedSettings "is dropped by default" when an IT-managed tier exists on the machine. In that case the post-start check is the only guard for a named list, and it sees only the servers present at open. allowedMcpServers is also what covers "agent frontmatter, plugins" for named lists, and with the allowlist dropped, nothing covers MCP servers declared in an agent file. Those start only when that sub-agent runs, after the check.

Scenario:

  • An IT-managed Claude policy is present (any keys; it need not touch MCP).
  • The thread's profile is { servers: ["docs"] }, and the user's Claude config has only docs, so the check passes.
  • The project's .claude/agents/researcher.md declares mcpServers: { github: … }.
  • The thread runs the researcher agent and gets mcp__github__*. There is no refusal.

A similar case for t3-only is unverified. Strict mode keeps "servers declared by explicitly-passed agent definitions". If a --agents '{…"mcpServers"…}' in the user's Claude launch args counts as explicitly passed (it goes through untouched in extraArgs), a t3-only thread gets that server when the agent runs.

Suggested fix: enforce at call time as well as at open. Add a PreToolUse hook (hooks run even under bypassPermissions, unlike canUseTool). For any mcp__<server>__… tool whose server is neither in plan.servers nor one of T3's own, return a deny with the same message. That also covers decision 4 (a server added mid-session). At the least, the README should name this gap.

2. SHOULD-FIX: with no profile set, a failed settings read now refuses every Claude turn

apps/server/src/fork/claudeMcpProfile.ts:190-197

getSettings is getMaterializedSettings, which reads every redacted provider secret from the server secret store (serverSettings.ts:972-995). Any secretStore.get failure returns ServerSettingsError, and the failure is not cached, so it repeats on every turn. Before this PR that did not affect Claude turns: upstream's own use of getSettings in the adapter, idle compaction at :12621, falls back with orElseSucceed.

Now a secret-store read error for an unrelated provider instance refuses every Claude thread with "could not read this thread's MCP profile settings", even for an owner who has never set a profile. That breaks "with no profile set, behaviour must be exactly as before".

Suggested fix: the four MCP keys need no secrets, so read them from the unmaterialized settings (or an MCP-only accessor). Refuse only when that read fails.

3. SHOULD-FIX (owner decision; the PR flags it as decision 2): a remote parent is treated more loosely than a local one

apps/server/src/fork/claudeMcpProfile.ts:135, 152-157

A local child whose parent cannot be read is refused, which matches #101. A child delegated from another machine has parentThreadId: null, so it never reaches the parentMissing check. With the sub-agent rule inherit (the default), it quietly gets this machine's mcpProfile.

Scenario: on machine B the owner has set mcpProfile: "all" plus one thread pick, so lineage is needed. A delegated child arrives from a t3-only parent on machine A. It starts with every outside server on B, with no refusal. A local orphan child in the same settings would be refused.

Server names on two machines need not mean the same servers, so "use B's default" may be the right call. But it should be a stated choice in the docs. Also, the comment at :152 says "(or on another machine)", and that case never reaches this branch.

4. NIT: the live-query key relies on object identity and has no test

claudeMcpProfile.ts:168, 201 and ClaudeAdapterV2.ts:3562

The plan's part of the key travels in a WeakMap keyed by the mcpOverrides object. Today there is exactly one caller, and it passes the same object, so the key is correct; I checked that all leaves the key byte-identical, because JSON.stringify drops an undefined property.

But if a future caller passes a copied or rebuilt overrides object, it silently gets the all key. The live process is then reused across a narrowing change (all → t3-only), with no refusal. No test covers "a profile change between turns opens a new process; the same profile reuses it". One adapter test with two turns would lock this down. Minor point: the key keeps list order, so ["a","b"] and ["b","a"] restart the process needlessly.

5. NIT: the post-start status call has no timeout

claudeMcpProfile.ts:216

When the thread has no T3 MCP session (mcpServers undefined), the runner's open does not wait for CLI init, so mcpServerStatus() is the first thing that waits on boot. Upstream bounds boot with CLAUDE_BOOT_TIMEOUT because "the SDK leaves query() boot unbounded". A hung boot now hangs the turn start inside the check instead of refusing. Wrapping the check in a timeout that maps to the "could not check" refusal fixes this.

6. NIT: more refusals than needed (not wider)

claudeMcpProfile.ts:153 refuses when any ancestor is missing and the thread itself has no pick. That holds even when an intermediate ancestor's pick makes the missing grandparent irrelevant (the resolver stops at a pick). This is safe, but it gives a confusing message.

State question: checked and OK

  • Runs again: settings are read on every turn. A changed plan changes the key, so the process is replaced, or upstream's background-work refusal applies. The same plan reuses the process, which was checked at open.
  • Continuation turns are refused while the profile cannot apply. They never widen.
  • Profile deleted or renamed mid-thread: the next turn gets the "missing" refusal, and the old process is left running.
  • Stops half-way: a failed post-start check closes the new process. The previous one was already closed by then, which is the same state as any failed open.
  • Old, empty or invalid settings:
    • no mcpProfiles key → all, with no lineage read;
    • unknown name → refused;
    • [] → strict;
    • a server named but not configured → allowlisted harmlessly, and the check passes;
    • a looping or too-deep lineage → refused.
  • Strict mode drops plugin servers and connectors: the SDK text matches the PR's answer, and strict also drops subagent-frontmatter MCP.

Tests

  • At head: the 3 fork MCP test files pass (63 tests). ClaudeAdapterV2.test.ts and ProviderTurnStartService.test.ts pass 547 of 548. The one failure is "forks a session from its original directory…", which is environmental (libatomic.so.1 is missing on this machine), as the PR says.
  • With the 12 upstream lines reverted (git checkout origin/main on the 3 files): claudeMcpProfile.adapter.test.ts fails 4 of 5 (t3-only, allowlist, missing-profile refusal, leaked-server refusal). The default-case test passes, as expected. This confirms the PR's claim.
  • The "No database schema changes" check failure was ignored as briefed (fork seams: announce the seam lines of MCP profiles part 2 (step 1) #527).

…de-servers

# Conflicts:
#	.github/fork-seams.json
Fix round for the two reviews of PR 528:
- Call-time guard: a profile other than all adds a PreToolUse hook that
  refuses a tool call (or an MCP resource read) to a server outside the
  profile, in every permission mode and inside sub-agents. Covers a managed
  policy that drops T3's allowlist, agent-file servers and servers added
  mid-session. The adapter merges it into its own hooks (one seam line,
  announced in PR 533).
- No-profile path: a failed settings read (it reads provider secrets too)
  refuses only when the settings last read had a profile set; otherwise the
  thread gets all, with a warning, as upstream's own reads fall back.
- Reuse key: overrides with no worked-out plan get a key no other turn has,
  so a reordered or rebuilt key line opens a new process instead of reusing
  a wider one; a two-turn test locks reuse and replacement.
- The start-time server check times out after 5 minutes and then refuses.
- The leaked-server refusal names --mcp-config in the Claude launch
  arguments; a missing settings service is logged.
- A task delegated from another machine keeps this machine's profile for
  its role: comment and docs say so; carrying the parent's profile is #532.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
scuttletoby added a commit that referenced this pull request Nov 19, 2026
)

Announces one more ClaudeAdapterV2.ts line for MCP profiles part 2: the
adapter merges the profile's PreToolUse hook (the call-time guard that
refuses a tool call to a server outside the thread's profile) into its own
hooks. Joins the existing announcement of 2026-11-19 and updates the entry's
why. List only; #528 adds the line and moves it to "added".

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…de-servers

# Conflicts:
#	.github/fork-seams.json
@scuttletoby

Copy link
Copy Markdown
Owner Author

Verify (fix round 1, Opus)

Checked head 3f3f0ad7 on a fresh clone. I diffed 42163093 against its parent and re-read the adapter wiring (makeClaudeQueryOptions, openQuery, the query runner's open path). I read the SDK 0.3.321 sdk.d.ts hook and settings text, and the Claude Code 2.1.325 CLI code for how hooks are filtered.

Verdict: 1 BLOCKING, 2 SHOULD-FIX, 2 NIT. The call-time guard, the reuse key and the timeout are sound. The new failed-settings-read rule opens a path where a set profile silently becomes all.

Tests run

  • The three MCP profile files: 76/76 pass. ClaudeAdapterV2.test.ts: 467/467 pass (the libatomic test passes on this host).
  • I put the parent's claudeMcpProfile.ts back, with stub exports only, and ran the new tests: 7 fail, as the PR says. They are the call-time refusal (adapter), 3 rows of the guard table, the fail-closed key, the no-profile fallback, and the timeout.
  • Mutation: I moved the queryPolicyKey line above the profile line. "a narrowed profile opens a new Claude process; the same profile reuses it" then fails. The lock works.

Review items

Review 1 (12:53Z)

# Item Status
1 Comment says a remote parent refuses FIXED. claudeMcpProfile.ts:238-240 and docs/fork/README.md:277-280 now describe the real behaviour; #532 tracks carrying the parent's profile. Docs only, so no test is needed.
2 Plan key found by object identity, no test FIXED within the seam limit. The WeakMap stays, but an unplanned overrides object now gets a key no other turn has (claudeMcpProfile.ts:251-259). The two-turn adapter test locks both directions (mutation above).
3 Steer keeps the old process FIXED (docs, README.md:273-275).
4 Post-start check runs once FIXED by the PreToolUse guard (claudeMcpProfile.ts:150-169). Tested at adapter level and in the guard table.
5 Leak refusal names only a managed policy FIXED (claudeMcpProfile.ts:69-70, 357). No test asserts the new start-time text; it is text only, so that is fine.
6 No settings service: silent all FIXED (claudeMcpProfile.ts:280-284, one warning per adapter).

Review 2 (12:54Z)

# Item Status
1 Servers that start after the one-time check FIXED by the PreToolUse guard. See the guard checks below and SHOULD-FIX 2 for one gap.
2 Failed settings read refuses every turn with no profile FIXED for the case reported, but the fix creates BLOCKING 1.
3 Remote parent FIXED (same as review 1 #1).
4 Key identity, no two-turn test FIXED. The list-order sub-nit (["a","b"] vs ["b","a"] restarts the process) is not addressed; that is harmless.
5 No timeout on the status call FIXED (claudeMcpProfile.ts:348), tested with TestClock.
6 Any missing ancestor refuses, even past a pick NOT FIXED. It errs on the safe side; fine to leave.

The call-time guard: checked and fine

  • Default path unchanged. all returns ALL_PLAN with options: {}, so no hooks key and no strictMcpConfig/managedSettings. ...input.mcpProfileOptions?.hooks spreads nothing. checkClaudeSession returns at once. The key gets mcpProfile: undefined, which JSON.stringify drops, so it is byte-identical. The adapter test asserts that no PreToolUse hook exists.
  • Merge with upstream hooks. openQuery always passes onStop, so the merged hooks object (ClaudeAdapterV2.ts:2349-2357) always replaces the top-level hooks from the earlier ...input.mcpProfileOptions spread. The profile's PreToolUse goes first, then upstream's SubagentStart/Stop. Upstream has no PreToolUse today, so nothing is dropped or reordered. If upstream adds one later, its key would replace the fork's, and the adapter test ("refuses, at the call…") would fail. Good.
  • Built-in tools, T3's own server, named servers. Non-mcp__ tools pass. T3's names come from overrides.mcpServers keys, and named servers match by configured name (mcp_server.name) or by the normalised prefix. mcp__a vs mcp__ab: the prefix check includes the trailing __, so mcp__ab__x does not match a. Correct.
  • Permission modes and managed hook switches. In the 2.1.325 CLI, registered SDK callback hooks have no pluginRoot. They are kept even under a managed disableAllHooks: the hook lookup filters only pluginRoot/deviceOwner entries in that case. They also count as managed-equivalent under allowManagedHooksOnly. So the guard survives the very managed policy it is meant to cover.
  • Reuse. The hook is bound when the process opens. A reused process has the same key, so the same server list. No path reuses a wider process: an unplanned key is unique, and a refused plan returns before the key is computed.
  • Timeout. checkMcpProfile is tapped after installationGate.execute, so it does not hold the gate. Worst case is bounded: boot 5 min, registration 90 s, check 5 min. With a T3 MCP session, boot has already been awaited, so the check returns quickly. Nothing hangs a turn without a limit.

New findings

BLOCKING 1: after a restart or adapter rebuild, a failed settings read turns a set profile into all.
apps/server/src/fork/claudeMcpProfile.ts:296, 302-315

lastConfigured starts false in every new makeClaudeMcpProfiles. That covers each server start, and also each Claude adapter rebuild: the instance registry rebuilds adapters on a config change or a secret rotation. The flag only becomes true after a successful read. A read that fails before then returns ALL_PLAN: no strict mode, no allowlist, no PreToolUse hook. The only trace is a server-log warning.

Scenario:

  • The owner's settings have mcpProfile: "t3-only".
  • T3 restarts.
  • A redacted provider secret, for any provider instance, cannot be read: an unreadable secret file, or an external secret provider that is locked. getMaterializedSettings fails, and the failure is not cached, so every read fails the same way.
  • Every Claude thread then starts with every outside server and no call-time check, until a read succeeds. This holds for every turn, not one.

This contradicts the PR's "Guaranteed" paragraph and #101 (refuse, never widen). The "Not guaranteed" list names only "a profile set in the very settings change whose read then fails". The log text "no profile was set when last read" is also wrong here, because nothing was read.

In this failure case the settings file itself was read. Only the secret materialisation failed, so the MCP keys are known; they are just thrown away.

Fix: decide from the settings, not from memory. On a failed read, read the MCP keys without secrets, and refuse only if that read also fails. That could be one fork accessor on the settings service that returns the cached, unmaterialised settings (getSettingsFromCache), announced as a seam line. Keeping lastConfigured as a cache is fine, but it must not be the source of truth after a restart.

Test: a fresh makeClaudeMcpProfiles whose file sets t3-only and whose first read fails with read-secret must refuse. Today it returns all. Please also add the restart case to the PR's state-question section.

SHOULD-FIX 2: an outside server's MCP prompts may be reachable through the Skill tool (likely; not confirmed live).
apps/server/src/fork/claudeMcpProfile.ts:126-145

The guard checks only mcp__… tool names and the two resource tools. In the 2.1.325 CLI, prompt commands with loadedFrom === "mcp" are gathered for model invocation unless disableModelInvocation is set. So Claude can likely run an MCP server's prompt via the Skill tool. That calls the server (prompts/get) and puts its output in the context.

Scenario:

  • A thread's profile is { servers: ["docs"] }.
  • A sub-agent's agent file declares github. It starts after the start-time check, so only the call-time guard can stop it.
  • Claude calls Skill with the github prompt's command name. The guard sees tool_name: "Skill" and allows it.

Fix: also refuse Skill (and SlashCommand, if still present) when the input names an MCP prompt of a server outside the profile. Confirm the exact command naming (mcp__<server>__<prompt> and/or <server>:<name>) with a no-prompt live probe, as the PR's own probes did. If it turns out not reachable, say so in the PR.

SHOULD-FIX 3: upstream's "invalidates live-query reuse when MCP credentials rotate" test now passes without testing anything.
apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts:710-733, caused by claudeMcpProfile.ts:258-259

That test calls claudeEffectiveQueryPolicyKey directly with overrides that were never planned. Since the fix, each call gets a unique unplanned key, so assert.notEqual always holds. Verified: with mcpServers: mcpOverrides.mcpServers removed from the key, the test still passes. So a later merge that broke token-rotation restarts would go unnoticed.

Fix: add a fork test that plans both overrides first (through the makeClaudeMcpProfiles function) and then compares the keys: equal for the same token, different after a rotation. Or extend the two-turn adapter test with a rotated MCP session.

NIT 4: ListMcpResourcesTool without server passes.
claudeMcpProfile.ts:139-142

With no server input it lists the resources of every connected server, including outside ones. That is only names, URIs and descriptions, since reads are refused. Either deny it when server is missing (T3's own server lists no resources), or add it to "Not guaranteed".

NIT 5: the prefix fallback also collides through normalisation.
claudeMcpProfile.ts:103-108, 133-137

A profile entry my.docs normalises to my_docs. On a CLI that sends no mcp_server, an outside server literally named my_docs then passes. This is the same class as the documented docs__x case; one more clause in "Not guaranteed" covers it.

State question

  • Runs again: the plan is rebuilt every turn; the same plan reuses the process and a narrower one replaces it. Fine.
  • Server restart, or adapter rebuild, with no prior read: BLOCKING 1.
  • Old or empty settings: decode to all, no hook, no status call. Fine.
  • Unparseable settings.json: loads as defaults, so all. This is upstream's rule and is documented.
  • Read fails half-way (file read, secret read fails): this is exactly the BLOCKING 1 path, because the MCP keys were read but are discarded.
  • Read fails after a successful read with a profile: refuses. Tested.
  • Read fails with none set: all plus a warning. Tested.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants